:- module(probe).
:- export get_probect / 1.
:- export set_probect / 1.
:- export add_con / 3.
:- export set_up_probe / 5.
:- comment(summary, "Probing").
:- comment(author, "Mark Wallace, Hani El Sakkout").
:- comment(date, "$Date: 2004/12/03 16:33:38 $").
:- comment(copyright, "Imperial College London and Parc Technologies").
:- comment(desc, html("<P>\n    This implementation of probing is a call to an external linear solver, \n    whose optimal solution is assigned to the problem variables as tentative \n    variables.\n</P><P>\nA counter is created an initialised to zero.  At every probe it is incremented.\nThe counter can be set using <B>set_probect(N)</B>, and can be read using \n<B>get_probect(N)</B>\n</P>")).
:- comment(add_con / 3, [summary : "Add a constraint to the fd and linear solvers", amode : add_con(+, ++, +), args : ["Constraint" : "A numerical constraint, with functor \n                         '=:=', '>=', '=<', '>' or '<'", "Options" : "An options structure", "Handle" : "A linear solver handle"], resat : no, see_also : [set_up_probe / 5], desc : html(" <P>\nIf the inequality is strict, <B>X>Y</B> or <B>X'<'Y</B>, then the granularity \n specified in the options is added to the smaller term to create a non-strict \n inequality, which can be passed to the linear solver.  Thus if the granularity\n is 3, then for <B>X>Y</B> the constraint <B>X>=Y+3</B> is added to the \n linear  solver and  <B>X#>=Y+3</B>  is added to the fd solver.\n</P>\n")]).
:- comment(set_up_probe / 5, [summary : "Sets up a linear probe for a set of constraints", amode : set_up_probe(+, +, -, ++, -), args : ["Tasks" : "A term containing some variables", "Constraints" : "A list of numerical constraints", "Cost" : "A cost variable", "Options" : "An options structure", "Handle" : "A variable which will record the handle of the matrix \nused by the linear solver"], resat : no, see_also : [probe_cstr_sched / 7, add_con / 3, lp_demon_setup / 5], desc : html("<P>\nThe constraints are passed to <B>add_con</B>, which adds them to both the \nfd and linear solvers.  The cost is declared to be an integer.  All the \nfinite domain variables in the term <B>Tasks</B> are associated with a demon \nwhich forwards their bounds to the linear solver.  (The priority of this \ndemon is one higher than that of the probe.)\n</P><P>\n<B>lp_demon_setup</B> is then invoked to set up the linear solver, with the \npriority specified in the <B>Options</B> parameter.  Solutions returned\nby the linear solver are automatically used to update the tentative values  \nof all the variables.\n</P>\n"), eg : "\n?- Options = options{granularity:3,priority:5},\n   Cost=X1,\n   set_up_probe([X1,X2,X3],[X1>X2,X2>X3],Cost,Options,H).\n"]).